package com.southminority.ethnic.service.news;

import com.southminority.ethnic.common.result.PageResult;
import com.southminority.ethnic.dto.NewsDTO;
import com.southminority.ethnic.controller.news.vo.NewsVO;
import com.southminority.ethnic.pojo.News;

import java.util.List;

/**
 * 新闻资讯服务接口.
 * <p>
 * 定义了新闻资讯模块的核心业务逻辑，包括前端展示和后台管理的所有功能。
 *
 * @author SouthMinority
 */
public interface NewsService {

    // =================================================================================
    // ==                             前端展示相关方法 (Public API)                     ==
    // =================================================================================

    /**
     * 分页查询已发布的新闻列表（用于前端列表页）。
     *
     * @param page            当前页码.
     * @param size            每页显示数量.
     * @param keyword         搜索关键词 (可选, 模糊匹配标题、摘要).
     * @param category        分类 (可选, 精确匹配).
     * @param newsType        新闻类型 (可选, 'news', 'progress', 'announcement').
     * @param organizationId  归属机构ID (可选)。
     * @return {@link PageResult<NewsVO>} 封装了分页信息的查询结果.
     */
    PageResult<NewsVO> getPublishedNewsPage(Integer page, Integer size, String keyword, String category, String newsType, Long organizationId);

    /**
     * 根据ID获取单个已发布新闻的详细信息（用于前端详情页）。
     * <p>
     * 此方法会增加文章的浏览次数.
     *
     * @param id 新闻的唯一标识ID.
     * @return {@link NewsVO} 包含完整内容的新闻视图对象.
     */
    NewsVO getPublishedNewsDetail(Long id);

    /**
     * 获取置顶新闻列表（用于首页轮播图或置顶区域）。
     * <p>
     * 只返回状态为“已发布”、is_top为1且包含封面图片的新闻。
     *
     * @param limit 获取数量限制.
     * @return {@link List<NewsVO>} 置顶新闻列表.
     */
    List<NewsVO> getTopNewsList(Integer limit);

    /**
     * 获取所有不重复的新闻分类列表（用于前端筛选菜单）。
     *
     * @return {@link List<String>} 分类名称字符串列表.
     */
    List<String> getNewsCategories();


    // =================================================================================
    // ==                             后台管理相关方法 (Admin API)                      ==
    // =================================================================================

    /**
     * 分页查询新闻列表（后台管理专用）。
     * <p>
     * 根据条件分页查询新闻，用于后台管理界面。支持按关键词、分类、新闻类型、状态、置顶状态等条件过滤。
     *
     * @param page       页码 (必填, 从1开始).
     * @param size       每页条数 (必填, 建议在1-100之间).
     * @param keyword    关键词 (可选, 模糊匹配标题).
     * @param category   分类 (可选, 精确匹配).
     * @param newsType   新闻类型 (可选, 如"news"、"progress"、"announcement").
     * @param status     状态 (可选, 1-已发布, 0-草稿, -1-已删除).
     * @param isTop      是否置顶 (可选, 1-是, 0-否, null-不限).
     * @return {@link PageResult<NewsVO>} 封装了分页信息的查询结果.
     */
    PageResult<NewsVO> getNewsPageForAdmin(Integer page, Integer size, String keyword, String category, String newsType, Integer status, Integer isTop);

    /**
     * 根据ID获取新闻详情（用于后台管理编辑页）。
     * <p>
     * 此方法会返回包括草稿在内的所有状态的新闻信息。
     *
     * @param id 新闻的唯一标识ID.
     * @return {@link NewsVO} 包含完整信息的新闻视图对象.
     */
    NewsVO getNewsDetailForAdmin(Long id);

    /**
     * 创建一篇新的新闻.
     *
     * @param news 包含新闻所有信息的POJO对象.
     * @return {@link NewsVO} 创建成功后返回的新闻视图对象.
     */
    NewsVO createNews(News news);

    /**
     * 更新一篇已存在的新闻.
     *
     * @param id   要更新的新闻的ID.
     * @param news 包含更新后信息的POJO对象.
     * @return {@link NewsVO} 更新成功后返回的新闻视图对象.
     */
    NewsVO updateNews(Long id, News news);

    /**
     * 根据ID删除一篇新闻（逻辑删除）。
     *
     * @param id 要删除的新闻的ID.
     * @return 操作成功返回true, 否则返回false.
     */
    boolean deleteNews(Long id);

    /**
     * 批量删除新闻（逻辑删除）。
     *
     * @param ids 包含多个要删除的新闻ID的列表.
     * @return 操作成功返回true, 否则返回false.
     */
    boolean batchDeleteNews(List<Long> ids);

    /**
     * 更新指定新闻的状态.
     *
     * @param id     新闻的ID.
     * @param status 新的状态值 (例如: 1-已发布, 0-草稿).
     * @return 操作成功返回true, 否则返回false.
     */
    boolean updateNewsStatus(Long id, Integer status);

    /**
     * 设置或取消新闻的置顶状态.
     *
     * @param id    新闻的ID.
     * @param isTop 是否置顶 (1-是, 0-否).
     * @return 操作成功返回true, 否则返回false.
     */
    boolean setNewsTopStatus(Long id, Integer isTop);
} 